Overview

The Ring control rings either a station set specified by the number to dial property, translated as a DN according to the station set dialling plan, or the station set on the current channel if R is specified. The Ring control can be used in the call-flow of an incoming line, and automatically dial a station set, wait for answer while providing ringback tone to the caller, and then bridge the calls if answered. In addition, it can be used in the call-flow for a station set channel, to ring that station only. In this case, a separate call-flow is used to provide ringback to the caller.

Automatic Bridging

Any voice resource used by a Station Set channel should be released after the call is answered, and the call should then enter a Delay control to wait for the call termination. The Delay control keeps the call active for the duration after the call is connected until one of the bridged callers disconnects.

How to Use Ring Control in a PBX Application

In this type of application, an incoming call, or a call originating from a station set, is connected to a station set, or to an outside line, after some numbers have been collected from the caller.

The Ring control is used to ring the local station. It can be used in two different ways - a one call-flow model and a two call-flow model.

In the one call-flow model, the Ring control is used to ring the station specified by the Ring control. The control will provide ringback tone to the caller while the station is ringing and will bridge the two channels automatically after the called station answers. The bridge will be disconnected automatically after the call terminates. This model makes use of the Ring control very simple and is suitable for most applications, but it lacks some of the flexibility of the two call-flow model.

In the two call-flow model, a call is started on a Station Set channel using the LineGroup StartCall method when required, and the Ring control is then used to ring that station. After answer, this call can be bridged to the originating call if appropriate using VB code or the conference control. The calls are un-bridged automatically when the call terminates.

One Call-flow Model

This model uses the Ring control to ring a local station with the given dialling number (DN) which is specified in the Number to Dial field in the property page. This number is translated to a physical station set using the dialling Plan.

The use of the Ring control in this model is similar to the use of the Dial control. The control is put in the call-flow when it is required to ring a local station with the specified dialling number - usually this is after a number to connect has been received by a GetDigits control. The call exits the control. The Ring control plays ring-back tone automatically while the station set is ringing and performs channel bridging when the set goes off-hook. Un-bridging is done automatically by the system when either call terminates.

Ring-back Tone

The ring-back tone is stored in a wave file, ringback.wav, in the VBVoice directory. This file can be replaced with any other WAV file of the same name. The default file is a normal North American ring-back tone - 2 seconds on, 4 seconds off.

Two call-flow Model

Two call-flows are used to handle a call to connect a local station. One call-flow is used to handle the incoming call activity and another call-flow is used to handle the local station activity. All the channel bridging must be done by VB code or by using a Conference control. The un-bridging will be done automatically when either of the calls end. If ring-back tone is needed it must be provided in the call flow explicitly. VB code must correlate the operations between the two call-flows as necessary - to start the ringing of the station set and to terminate the ringback tone when the station set answers or times out.

The incoming call must start a second call on a station set using the LineGroup StartCall method. A Ring control with R in the Number to Dial field is then used on that call-flow to ring the current local station channel. If the station answers, the ringback tone being played to the original caller should be terminated by VB code, and the two channels bridged together.

Initial Setup Properties

ClearDigits

(Boolean)

If True, the digit buffer is cleared when a call enters the control.

DisconnectControl

(String)

See Responding to Caller Hangup.

INumToDial

(String)

Initial value of the number to be dialled that identifies the destination MSI line.

NumofRings

(Integer)

Number of rings before the control exits through the NoAnswer exit node.

Runtime Properties

CallResult

(Integer)

This property contains an integer value that represents the result of the last call. Possible values are

• vbvBusy

• vbvNoAnswer

• vbvConnected

CallTime

(String)

This property contains a formatted string representing the start time of the last call. The string is formatted as mm/dd/yy hh:mm, using a 24 hour notation.

GotoNode

See GotoNode.

NumToDial

(String)

The number to be dialled to identify the destination MSI line.

Greeting Properties

EntryGreeting

This greeting will play when the call first enters the control. If no call is established, for example when a new call is being initiated, this greeting should be left empty.

Methods

TakeCall

This method allows the programmer to override the graphical connections and transfer a call to any other control. See TakeCall.

Events

Disconnect

Sub xx_Disconnect (ByVal Channel as Integer, ByVal Reason as Integer)

This event is fired when a caller hangs up and it can occur in any control that performs voice processing. This event allows clean-up on a per-control basis. After it occurs, a Disconnect event occurs in the LineGroup control that initiated this call. Read more about Disconnect Event.

Enter

Enter(Channel As Integer, Greeting As Object)

The Enter event is executed by the control upon call entry. If the GotoNode property is set or the TakeCall method is used, the call exits this control and is handled by the new control after the Exit Sub or End Sub statement. Read more about Enter Event.

Exit

Exit(Channel As Integer, Node As Integer)

This event fires when a call leaves a control, but before the Enter event occurs in the destination control. Read more about Exit Event.

PhraseError

PhraseError(ByVal Channel as Integer, Phrase as Object, ByVal ErrType as Integer)

This event is fired when VBVoice cannot open a specified file; when VBVoice cannot find a specified phrase within a file; when an invalid parameter is specified in a System Phrase. Read more about PhraseError Event.

PlayRequest

Sub PlayRequest(ByVal Channel as Integer, ByVal PhraseName as String, Phrase as Object)

This event occurs when a greeting contains a VB Phrase. Every VB Phrase is named so that it can easily be identified in a situation where a control has multiple VB Phrases. Read more about PlayRequest Event.

VoiceError

VoiceError(Channel as Integer, ErrorType as Integer, ErrorData as Integer, Processed as Integer)

This event fires when a non-fatal error occurs in the control. When this error event occurs, the control generating the event is generally not able to continue normal processing. Read more about VoiceError Event.

Setup Property Page

Number to dial

A station dialling number or a capital R. If R is specified, the station set for the current channel will ring. This option is used in the two call-flow model. If a station dialling number is set, it will be mapped to a station set using the dialling plan. This option is used in the one call-flow model.

Number of rings

Indicates the number of rings that a station will ring before returning no answer.

Set the number to be 0 if you use a headset. Otherwise the number must be greater than 2.

Zip-tone

If the Station Set card does not have ring capability, set the number of rings to be 0. In this scenario the Ring control will generate a short tone on the corresponding phone or headset.

Ring Control Examples

One call-flow model

This example demonstrates:

1. A call on a digital line from CO or PBX ringing a specified local station

2. A call on an analog line from CO or PBX ringing a specified local station

3. An station making an internal or external call.

Read more about the MSI1Flow example.

Digital trunk calls a station

This example only needs to start a call-flow on one channel to handle a call between two stations or between a station and an external line.

The functionality provided is as follows:

1. Answer an incoming call

2. Get voice resource from a specified voice resource group

3. Play greeting

4. Get a specified station number

5. Ring the specified station

If the station answers the call, it releases the associated voice resource, connects the caller to the extension and then enters a delay control to wait for the call termination. If the station does not answer, it goes back to the caller and asks for a new extension.

The DigitalGrp control answers incoming calls and passes the call to the GetResource2, which allocates a voice resource to the channel. A greeting is played to the caller in PlayGreeting1, and then GetDigits1 is used to get a number to dial. This is passed to the Ring1 control using a dial string of %GetDigits1.Digits%. While the station set rings, the Ring control plays ringback to the caller using the allocated voice resource. If the station answers, the call exits out of the Answer output and is automatically bridged. The voice resource is freed and the Talk control is used to wait silently for the end of the call. If the call is not answered, the call is routed back to the GetDigits1 control to get another extension to try.

Analog trunk calls a station

This page shows the call-flow required for an analog trunk to accept a number from an incoming call on an analog line, and dial the station set. It is identical to the call-flow described above, except that the analog line has a dedicated voice resource so does not require the GetResource and FreeResource controls.

MSI stations make internal and external calls

This page shows the call-flow required to initiate a call from a station set to an external line.

When a station set goes offhook, the call exits out of the Offhook output of the LineGroup control, and enters the GetResource1 control to allocate a voice resource. The Delay control is used to play dial-tone to the caller until a digit is pressed. The DialTone control then collects the required digits (4 digits in this case). A User control (CheckNumber) is used to test whether the number provided identifies a local station set or a number that should be dialled externally.

If the number is a local station set, the Ring control is used to ring the specified station. The Ring control plays ringback to the caller until the call is answered or another call result is obtained. If the call is answered, the voice resource is released, and a Delay control (WaitForDisc) then waits for the call termination. If another call result is obtained, the call routes back to the GetDigits3 control to get another extension.

If the number is not in the dialling plan, it is assumed to be external, the call exits from the Outcall output of the User (CheckNumber)control, to the Dial1 control. The Dial1 control gets a free channel from the designated pool of lines defined in the Outlines entry (see Ring Control) in vbvoice.ini, and dials the number on this channel, while playing ringback to the station set. When the call is answered, the two calls are bridged together.

Two call-flow model

The MSI2Flow example shows how to use the station set support using a separate call flow for each channel. All bridging and voice resource allocation must be performed by VB code, although un-bridging will be done automatically after the call goes on-hook.

The following functionality is provided:

1. A call on an incoming line from a CO/PBX is answered, the caller enters the extension, which is then used to ring the corresponding station set. Once the station set answers, the two calls are bridged together.

2. A station set is taken offhook - the system provides dialtone, accepts an extension, makes an internal or external call, and bridges the two calls together.

In order to handle this situation properly you have to carefully plan the channel bridging and voice resource usage. Separate call-flows are used for analog trunks, digital trunks, and for the station set control. When initiating an outside call, any free trunk line can be selected, and the number to dial must be passed to this channel - this is usually done using a Transfer property in the VBVFrame control. If initiating a call to an station set, the set is selected by starting a call on the appropriate channel for that set.

Digital Trunk handling

When an incoming call arrives on a digital line, it is answered by the DigitalGrp control. The GetResource2 control allocates a voice resource to the channel, and the GetStationNum control receives a 4 digit extension number. Code in the Enter event for the Wait1 control then stores the extension number in a Transfer property for the station set channel and starts a call on an station set channel (see Station Set handling below). The call then stays in the Wait1 Delay control until a call result is returned by the station set call, at which point the call either exits to the Talk1 Delay control for the duration of the conversation, or exits directly to the Onhook1 control in the case of no answer on the station set call.

When the station set call is started, it enters a Ring control (Ring1) which uses a dial string of R. This will ring the attached station set. If the call is answered, the call enters the Talk5 control, where the two calls are bridged together. The incoming call is meanwhile waiting in the Wait1 control, so the StopDelay function is used to terminate the delay for that channel, and then enters the Talk1 control (above). When either call terminates, both calls exit to an Onhook control.

Station Set handling

When a station set is taken offhook, the call-flow enters the GetResource control, and the DialTone/GetDigits1 controls play dialtone and accept an extension number. Code in the Enter event for the Wait control then starts an outbound call on a trunk, and waits for a call result. The outbound call exits out of the DigitalGrp control (see Digital Trunk handling above), and dials the number using the Dial1 control. If the call is answered, code in the Talk2 control stops the delay for the original station set call, bridges the two calls, and then enters a delay for the duration of the conversation.